Object Classes
commodity
A good or product that can be consumed, produced, traded. E.g., electricity, oil, gas, water...
Related Parameters: commodity_lodf_tolerance, commodity_physics_duration, commodity_physics, commodity_ptdf_threshold, mp_min_res_gen_to_demand_ratio_slack_penalty and mp_min_res_gen_to_demand_ratio
Related Relationship Classes: node__commodity and unit__commodity
Commodities correspond to the type of energy traded. When associated with a node through the node__commodity relationship, a specific form of energy, i.e. commodity, can be associated with a specific location. Furthermore, by linking commodities with units, it is possible to track the flows of a certain commodity and impose limitations on the use of a certain commodity (See also max_cum_in_unit_flow_bound). For the representation of specific commodity physics, related to e.g. the representation of the electric network, designated parameters can be defined to enforce commodity specific behaviour. (See also commodity_physics)
connection
A transfer of commodities between nodes. E.g. electricity line, gas pipeline...
Related Parameters: benders_starting_connections_invested, candidate_connections, connection_availability_factor, connection_contingency, connection_decommissioning_cost, connection_decommissioning_time, connection_discount_rate_technology_specific, connection_investment_cost, connection_investment_econ_lifetime, connection_investment_lifetime_sense, connection_investment_tech_lifetime, connection_investment_variable_type, connection_lead_time, connection_monitored, connection_reactance_base, connection_reactance, connection_resistance, connection_type, connections_invested_big_m_mga, connections_invested_mga_weight, connections_invested_mga, fix_connections_invested_available, fix_connections_invested, graph_view_position, has_binary_gas_flow, initial_connections_invested_available, initial_connections_invested and number_of_connections
Related Relationship Classes: connection__from_node__investment_group, connection__from_node__user_constraint, connection__from_node, connection__investment_group, connection__investment_stochastic_structure, connection__investment_temporal_block, connection__node__node, connection__to_node__investment_group, connection__to_node__user_constraint, connection__to_node, connection__user_constraint and stage__output__connection
A connection represents a transfer of one commodity over space. For example, an electricity transmission line, a gas pipe, a river branch, can be modelled using a connection.
A connection always takes commodities from one or more nodes, and releases them to one or more (possibly the same) nodes. The former are specificed through the connection__from_node relationship, and the latter through connection__to_node. Every connection inherits the temporal and stochastic structures from the associated nodes. The model will generate connection_flow variables for every combination of connection, node, direction (from node or to node), time slice, and stochastic scenario, according to the above relationships.
The operation of the connection is specified through a number of parameter values. For example, the capacity of the connection, as the maximum amount of energy that can enter or leave it, is given by connection_capacity. The conversion ratio of input to output can be specified using any of fix_ratio_out_in_connection_flow, max_ratio_out_in_connection_flow, and min_ratio_out_in_connection_flow parameters in the connection__node__node relationship. The delay on a connection, as the time it takes for the energy to go from one end to the other, is given by connection_flow_delay.## investment_group
A group of investments that need to be done together.
Related Parameters: equal_investments, maximum_capacity_invested_available, maximum_entities_invested_available, minimum_capacity_invested_available and minimum_entities_invested_available
Related Relationship Classes: connection__from_node__investment_group, connection__investment_group, connection__to_node__investment_group, node__investment_group, unit__from_node__investment_group, unit__investment_group and unit__to_node__investment_group
The investment_group class represents a group of investments that need to be done together. For example, a storage investment on a node might only make sense if done together with a unit or a connection investment.
To use this functionality, you must first create an investment_group and then specify any number of unit__investment_group, node__investment_group, and/or connection__investment_group relationships between your investment_group and the unit, node, and/or connection investments that you want to be done together. This will ensure that the investment variables of all the entities in the investment_group have the same value.
model
An instance of SpineOpt, that specifies general parameters such as the temporal horizon.
Related Parameters: big_m, db_lp_solver_options, db_lp_solver, db_mip_solver_options, db_mip_solver, discount_rate, discount_year, duration_unit, max_gap, max_iterations, max_mga_iterations, max_mga_slack, min_iterations, model_algorithm, model_end, model_start, model_type, monte_carlo_scenarios, report_benders_iterations, roll_forward, shared_values, use_connection_intact_flow, use_economic_representation, use_highest_resolution_constraint_ratio_out_in_connection_flow, use_milestone_years, use_tight_compact_formulations, window_duration, window_weight, write_lodf_file, write_mps_file and write_ptdf_file
Related Relationship Classes: model__default_investment_stochastic_structure, model__default_investment_temporal_block, model__default_stochastic_structure, model__default_temporal_block and model__report
The model object holds general information about the optimization problem at hand. Firstly, the modelling horizon is specified on the model object, i.e. the scope of the optimization model, and if applicable the duration of the rolling window (see also model_start, model_end and roll_forward). Secondly, the model works as an overarching assembler - only through linking temporal_blocks and stochastic_structures to a model object via relationships, they become part of the optimization problem, and respectively linked nodes, connections and units. If desired the user can also specify defaults for temporals and stochastic via the designated default relationships (see e.g., model__default_temporal_block). In this case, the default temporal is populated for missing node__temporal_block relationships. Lastly, the model object contains information about the algorithm used for solving the problem (see model_type).
node
A universal aggregator of commodify flows over units and connections, with storage capabilities.
Related Parameters: balance_type, benders_starting_storages_invested, candidate_storages, demand, downward_reserve, fix_node_pressure, fix_node_state, fix_node_voltage_angle, fix_storages_invested_available, fix_storages_invested, frac_state_loss, fractional_demand, graph_view_position, has_pressure, has_state, has_voltage_angle, initial_node_pressure, initial_node_state, initial_node_voltage_angle, initial_storages_invested_available, initial_storages_invested, is_longterm_storage, is_non_spinning, is_reserve_node, max_node_pressure, max_voltage_angle, min_capacity_margin_penalty, min_capacity_margin, min_node_pressure, min_voltage_angle, minimum_reserve_activation_time, nodal_balance_sense, node_opf_type, node_slack_penalty, node_state_cap, node_state_min, number_of_storages, state_coeff, storage_decommissioning_cost, storage_decommissioning_time, storage_discount_rate_technology_specific, storage_fom_cost, storage_investment_cost, storage_investment_econ_lifetime, storage_investment_lifetime_sense, storage_investment_tech_lifetime, storage_investment_variable_type, storage_lead_time, storages_invested_big_m_mga, storages_invested_mga_weight, storages_invested_mga, tax_in_unit_flow, tax_net_unit_flow, tax_out_unit_flow and upward_reserve
Related Relationship Classes: connection__from_node__investment_group, connection__from_node__user_constraint, connection__from_node, connection__node__node, connection__to_node__investment_group, connection__to_node__user_constraint, connection__to_node, node__commodity, node__investment_group, node__investment_stochastic_structure, node__investment_temporal_block, node__node, node__stochastic_structure, node__temporal_block, node__user_constraint, stage__output__node, unit__from_node__investment_group, unit__from_node__user_constraint, unit__from_node, unit__node__node, unit__to_node__investment_group, unit__to_node__user_constraint and unit__to_node
The node is perhaps the most important object class out of the Systemic object classes, as it is what connects the rest together via the Systemic relationship classes. Essentially, nodes act as points in the modelled commodity network where commodity balance is enforced via the node balance and node injection constraints, tying together the inputs and outputs from units and connections, as well as any external demand. Furthermore, nodes play a crucial role for defining the temporal and stochastic structures of the model via the node__temporal_block and node__stochastic_structure relationships. For more details about the Temporal Framework and the Stochastic Framework, please refer to the dedicated sections.
Since nodes act as the points where commodity balance is enforced, this also makes them a natural fit for implementing storage. The has_state parameter controls whether a node has a node_state variable, which essentially represents the commodity content of the node. The state_coeff parameter tells how the node_state variable relates to all the commodity flows. Storage losses are handled via the frac_state_loss parameter, and potential diffusion of commodity content to other nodes via the diff_coeff parameter for the node__node relationship.
output
A variable name from SpineOpt whose value can be included in a report.
Related Parameters: output_resolution and output_type
Related Relationship Classes: report__output, stage__output__connection, stage__output__node, stage__output__unit and stage__output
An output is essentially a handle for a SpineOpt variable and Objective function to be included in a report and written into an output database. Typically, e.g. the unit_flow variables are desired as output from most models, so creating an output object called unit_flow allows one to designate it as something to be written in the desired report. Note that unless appropriate model__report and report__output relationships are defined, SpineOpt doesn't write any output!## report
A results report from a particular SpineOpt run, including the value of specific variables.
Related Parameters: output_db_url
Related Relationship Classes: model__report and report__output
A report is essentially a group of outputs from a model, that gets written into the output database as a result of running SpineOpt. Note that unless appropriate model__report and report__output relationships are defined, SpineOpt doesn't write any output!## settings
Internal SpineOpt settings. We kindly advise not to mess with this one.
Related Parameters: version
stage
An additional stage in the optimisation problem (EXPERIMENTAL)
Related Parameters: stage_scenario
Related Relationship Classes: stage__child_stage, stage__output__connection, stage__output__node, stage__output__unit and stage__output
stochastic_scenario
A scenario for stochastic optimisation in SpineOpt.
Related Relationship Classes: parent_stochastic_scenario__child_stochastic_scenario and stochastic_structure__stochastic_scenario
Essentially, a stochastic_scenario is a label for an alternative period of time, describing one possibility of what might come to pass. They are the basic building blocks of the scenario-based Stochastic Framework in SpineOpt.jl, but aren't really meaningful on their own. Only when combined into a stochastic_structure using the stochastic_structure__stochastic_scenario and parent_stochastic_scenario__child_stochastic_scenario relationships, along with Parameters like the weight_relative_to_parents and stochastic_scenario_end, they become meaningful.## stochastic_structure
A group of stochastic scenarios that represent a structure.
Related Relationship Classes: connection__investment_stochastic_structure, model__default_investment_stochastic_structure, model__default_stochastic_structure, node__investment_stochastic_structure, node__stochastic_structure, stochastic_structure__stochastic_scenario, unit__investment_stochastic_structure and units_on__stochastic_structure
The stochastic_structure is the key component of the scenario-based Stochastic Framework in SpineOpt.jl, and essentially represents a group of stochastic_scenarios with set Parameters. The stochastic_structure__stochastic_scenario relationship defines which stochastic_scenarios are included in which stochastic_structures, and the weight_relative_to_parents and stochastic_scenario_end Parameters define the exact shape and impact of the stochastic_structure, along with the parent_stochastic_scenario__child_stochastic_scenario relationship.
The main reason as to why stochastic_structures are so important is, that they act as handles connecting the Stochastic Framework to the modelled system. This is handled using the Structural relationship classes e.g. node__stochastic_structure, which define the stochastic_structure applied to each object describing the modelled system. Connecting each system object to the appropriate stochastic_structure individually can be a bit bothersome at times, so there are also a number of convenience Meta relationship classes like the model__default_stochastic_structure, which allow setting model-wide defaults to be used whenever specific definitions are missing.## temporal_block
A length of time with a particular resolution.
Related Parameters: block_end, block_start, representative_period_index, representative_periods_mapping, resolution and weight
Related Relationship Classes: connection__investment_temporal_block, model__default_investment_temporal_block, model__default_temporal_block, node__investment_temporal_block, node__temporal_block, unit__investment_temporal_block and units_on__temporal_block
A temporal block defines the temporal properties of the optimization that is to be solved in the current window. It is the key building block of the Temporal Framework. Most importantly, it holds the necessary information about the resolution and horizon of the optimization. A single model can have multiple temporal blocks, which is one of the main sources of temporal flexibility in Spine: by linking different parts of the model to different temporal blocks, a single model can contain aspects that are solved with different temporal resolutions or time horizons.
unit
A conversion of one/many commodities between nodes.
Related Parameters: benders_starting_units_invested, candidate_units, curtailment_cost, fix_units_invested_available, fix_units_invested, fix_units_on, fix_units_out_of_service, fom_cost, graph_view_position, initial_units_invested_available, initial_units_invested, initial_units_on, initial_units_out_of_service, is_renewable, min_down_time, min_up_time, number_of_units, online_variable_type, outage_variable_type, scheduled_outage_duration, shut_down_cost, start_up_cost, unit_availability_factor, unit_decommissioning_cost, unit_decommissioning_time, unit_discount_rate_technology_specific, unit_investment_cost, unit_investment_econ_lifetime, unit_investment_lifetime_sense, unit_investment_tech_lifetime, unit_investment_variable_type, unit_lead_time, units_invested_big_m_mga, units_invested_mga_weight, units_invested_mga, units_on_cost, units_on_non_anticipativity_margin, units_on_non_anticipativity_time and units_unavailable
Related Relationship Classes: stage__output__unit, unit__commodity, unit__from_node__investment_group, unit__from_node__user_constraint, unit__from_node, unit__investment_group, unit__investment_stochastic_structure, unit__investment_temporal_block, unit__node__node, unit__to_node__investment_group, unit__to_node__user_constraint, unit__to_node, unit__user_constraint, units_on__stochastic_structure and units_on__temporal_block
A unit represents an energy conversion process, where energy of one commodity can be converted into energy of another commodity. For example, a gas turbine, a power plant, or even a load, can be modelled using a unit.
A unit always takes energy from one or more nodes, and releases energy to one or more (possibly the same) nodes. The former are specificed through the unit__from_node relationship, and the latter through unit__to_node. Every unit has a temporal and stochastic structures given by the units_on__temporal_block and [units_on__stochastic_structure] relationships. The model will generate unit_flow variables for every combination of unit, node, direction (from node or to node), time slice, and stochastic scenario, according to the above relationships.
The operation of the unit is specified through a number of parameter values. For example, the capacity of the unit, as the maximum amount of energy that can enter or leave it, is given by unit_capacity. The conversion ratio of input to output can be specified using any of fix_ratio_out_in_unit_flow, max_ratio_out_in_unit_flow, and min_ratio_out_in_unit_flow. The variable operating cost is given by vom_cost.## user_constraint
A generic data-driven custom constraint.
Related Parameters: constraint_sense, include_in_non_representative_periods, right_hand_side and user_constraint_slack_penalty
Related Relationship Classes: connection__from_node__user_constraint, connection__to_node__user_constraint, connection__user_constraint, node__user_constraint, unit__from_node__user_constraint, unit__to_node__user_constraint and unit__user_constraint
The user_constraint is a generic data-driven custom constraint, which allows for defining constraints involving multiple units, nodes, or connections. The constraint_sense parameter changes the sense of the user_constraint, while the right_hand_side parameter allows for defining the constant terms of the constraint.
Coefficients for the different variables appearing in the user_constraint are defined using relationships, like e.g. unit__from_node__user_constraint and connection__to_node__user_constraint for unit_flow and connection_flow variables, or unit__user_constraint and node__user_constraint for units_on, units_started_up, and node_state variables.
For more information, see the dedicated article on User Constraints